JavaScript Asynchrone Contextpropagatie: Request Tracing en Continuering met AsyncLocalStorage

In moderne server-side JavaScript-ontwikkeling, met name met Node.js, zijn asynchrone operaties alomtegenwoordig. Het beheren van state en context over deze asynchrone grenzen heen kan een uitdaging zijn. Deze blogpost verkent het concept van asynchrone contextpropagatie, met een focus op hoe AsyncLocalStorage kan worden gebruikt om request tracing en continuering effectief te realiseren. We onderzoeken de voordelen, beperkingen en praktijktoepassingen, en geven praktische voorbeelden om het gebruik ervan te illustreren.

Wat is Asynchrone Contextpropagatie?

Asynchrone contextpropagatie verwijst naar de mogelijkheid om contextinformatie (bijv. request-ID's, gebruikersauthenticatiegegevens, correlatie-ID's) te behouden en door te geven over asynchrone operaties heen. Zonder correcte contextpropagatie wordt het moeilijk om verzoeken te traceren, logs te correleren en prestatieproblemen in gedistribueerde systemen te diagnosticeren.

Traditionele benaderingen voor contextbeheer zijn vaak afhankelijk van het expliciet doorgeven van contextobjecten via functieaanroepen, wat kan leiden tot uitgebreide en foutgevoelige code. AsyncLocalStorage biedt een elegantere oplossing door een manier te bieden om contextgegevens op te slaan en op te halen binnen een enkele executiecontext, zelfs over asynchrone operaties heen.

Introductie van AsyncLocalStorage

AsyncLocalStorage is een ingebouwde Node.js-module (beschikbaar sinds Node.js v14.5.0) die een manier biedt om gegevens op te slaan die lokaal zijn voor de levensduur van een asynchrone operatie. Het creëert in wezen een opslagruimte die behouden blijft over await-aanroepen, promises en andere asynchrone grenzen heen. Dit stelt ontwikkelaars in staat om contextgegevens te benaderen en te wijzigen zonder deze expliciet door te geven.

Belangrijkste kenmerken van AsyncLocalStorage:

• Automatische Contextpropagatie: Waarden opgeslagen in AsyncLocalStorage worden automatisch doorgegeven over asynchrone operaties binnen dezelfde executiecontext.
• Vereenvoudigde Code: Vermindert de noodzaak om contextobjecten expliciet door te geven via functieaanroepen.
• Verbeterde Observeerbaarheid: Faciliteert request tracing en de correlatie van logs en metrics.
• Thread-Safety: Biedt thread-veilige toegang tot contextgegevens binnen de huidige executiecontext.

Toepassingen voor AsyncLocalStorage

AsyncLocalStorage is waardevol in diverse scenario's, waaronder:

• Request Tracing: Het toewijzen van een unieke ID aan elk inkomend verzoek en dit doorgeven gedurende de levenscyclus van het verzoek voor tracing-doeleinden.
• Authenticatie en Autorisatie: Het opslaan van gebruikersauthenticatiegegevens (bijv. user-ID, rollen, permissies) voor toegang tot beveiligde bronnen.
• Logging en Auditing: Het koppelen van verzoek-specifieke metadata aan logberichten voor betere debugging en auditing.
• Prestatiemonitoring: Het bijhouden van de uitvoeringstijd van verschillende componenten binnen een verzoek voor prestatieanalyse.
• Transactiebeheer: Het beheren van transactionele state over meerdere asynchrone operaties (bijv. databasetransacties).

Praktijkvoorbeeld: Request Tracing met AsyncLocalStorage

Laten we illustreren hoe AsyncLocalStorage kan worden gebruikt voor request tracing in een eenvoudige Node.js-applicatie. We maken een middleware die een unieke ID toewijst aan elk inkomend verzoek en deze beschikbaar maakt gedurende de gehele levenscyclus van het verzoek.

Codevoorbeeld

Installeer eerst de benodigde packages (indien nodig):

            npm install uuid express
            

              
                Copy
              
            
          

Hier is de code:

            // app.js
const express = require('express');
const { AsyncLocalStorage } = require('async_hooks');
const { v4: uuidv4 } = require('uuid');

const app = express();
const asyncLocalStorage = new AsyncLocalStorage();
const port = 3000;

// Middleware om een request-ID toe te wijzen en op te slaan in AsyncLocalStorage
app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    next();
  });
});

// Simuleer een asynchrone operatie
async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      const requestId = asyncLocalStorage.getStore().get('requestId');
      console.log(`[Async] Request ID: ${requestId}`);
      resolve();
    }, 50);
  });
}

// Route handler
app.get('/', async (req, res) => {
  const requestId = asyncLocalStorage.getStore().get('requestId');
  console.log(`[Route] Request ID: ${requestId}`);
  await doSomethingAsync();
  res.send(`Hello World! Request ID: ${requestId}`);
});

app.listen(port, () => {
  console.log(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

In dit voorbeeld:

1. We maken een AsyncLocalStorage-instantie aan.
2. We definiëren een middleware die een unieke ID toewijst aan elk inkomend verzoek met behulp van de uuid-bibliotheek.
3. We gebruiken asyncLocalStorage.run() om de request handler uit te voeren binnen de context van de AsyncLocalStorage. Dit zorgt ervoor dat alle waarden die in de AsyncLocalStorage zijn opgeslagen, beschikbaar zijn gedurende de gehele levenscyclus van het verzoek.
4. Binnen de middleware slaan we de request-ID op in de AsyncLocalStorage met asyncLocalStorage.getStore().set('requestId', requestId).
5. We definiëren een asynchrone functie doSomethingAsync() die een asynchrone operatie simuleert en de request-ID ophaalt uit de AsyncLocalStorage.
6. In de route handler halen we de request-ID op uit de AsyncLocalStorage en nemen deze op in het antwoord.

Wanneer u deze applicatie uitvoert en een verzoek stuurt naar http://localhost:3000, zult u zien dat de request-ID wordt gelogd in zowel de route handler als de asynchrone functie, wat aantoont dat de context correct wordt doorgegeven.

Uitleg

• AsyncLocalStorage-instantie: We maken een instantie van AsyncLocalStorage die onze contextgegevens zal bevatten.
• Middleware: De middleware onderschept elk inkomend verzoek. Het genereert een UUID en gebruikt vervolgens asyncLocalStorage.run om de rest van de verzoekafhandelingspijplijn *binnen* de context van deze opslag uit te voeren. Dit is cruciaal; het zorgt ervoor dat alles downstream toegang heeft tot de opgeslagen gegevens.
• asyncLocalStorage.run(new Map(), ...): Deze methode accepteert twee argumenten: een nieuwe, lege Map (u kunt andere datastructuren gebruiken als dat geschikt is voor uw context) en een callback-functie. De callback-functie bevat de code die binnen de asynchrone context moet worden uitgevoerd. Alle asynchrone operaties die binnen deze callback worden geïnitieerd, zullen automatisch de gegevens overnemen die in de Map zijn opgeslagen.
• asyncLocalStorage.getStore(): Dit retourneert de Map die aan asyncLocalStorage.run is doorgegeven. We gebruiken het om de request-ID op te slaan en op te halen. Als run niet is aangeroepen, retourneert dit undefined, daarom is het belangrijk om run binnen de middleware aan te roepen.
• Asynchrone Functie: De functie doSomethingAsync simuleert een asynchrone operatie. Cruciaal is dat, hoewel het asynchroon is (met setTimeout), het nog steeds toegang heeft tot de request-ID omdat het draait binnen de context die is ingesteld door asyncLocalStorage.run.

Geavanceerd Gebruik: Combineren met Logging-bibliotheken

Het integreren van AsyncLocalStorage met logging-bibliotheken (zoals Winston of Pino) kan de observeerbaarheid van uw applicaties aanzienlijk verbeteren. Door contextgegevens (bijv. request-ID, user-ID) in logberichten te injecteren, kunt u eenvoudig logs correleren en verzoeken traceren over verschillende componenten heen.

Voorbeeld met Winston

            // logger.js
const winston = require('winston');
const { AsyncLocalStorage } = require('async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.printf(({ timestamp, level, message }) => {
      const requestId = asyncLocalStorage.getStore() ? asyncLocalStorage.getStore().get('requestId') : 'N/A';
      return `${timestamp} [${level}] [${requestId}] ${message}`;
    })
  ),
  transports: [
    new winston.transports.Console()
  ]
});

module.exports = {
  logger,
  asyncLocalStorage
};

            

              
                Copy
              
            
          

            // app.js (aangepast)
const express = require('express');
const { v4: uuidv4 } = require('uuid');
const { logger, asyncLocalStorage } = require('./logger');

const app = express();
const port = 3000;

app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    logger.info(`Incoming request: ${req.url}`); // Log het inkomende verzoek
    next();
  });
});

async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      logger.info('Iets asynchroons doen...');
      resolve();
    }, 50);
  });
}

app.get('/', async (req, res) => {
  logger.info('Verzoek afhandelen...');
  await doSomethingAsync();
  res.send('Hello World!');
});

app.listen(port, () => {
  logger.info(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

In dit voorbeeld:

• We maken een Winston logger-instantie aan en configureren deze om de request-ID uit de AsyncLocalStorage in elk logbericht op te nemen. Het belangrijkste onderdeel is winston.format.printf, dat de request-ID (indien beschikbaar) ophaalt uit de AsyncLocalStorage. We controleren of asyncLocalStorage.getStore() bestaat om fouten te voorkomen bij het loggen buiten een verzoekcontext.
• We updaten de middleware om de URL van het inkomende verzoek te loggen.
• We updaten de route handler en de asynchrone functie om berichten te loggen met de geconfigureerde logger.

Nu zullen alle logberichten de request-ID bevatten, wat het gemakkelijker maakt om verzoeken te traceren en logs te correleren.

Alternatieve Benaderingen: cls-hooked en Async Hooks

Voordat AsyncLocalStorage beschikbaar kwam, werden bibliotheken zoals cls-hooked vaak gebruikt voor asynchrone contextpropagatie. cls-hooked gebruikt Async Hooks (een lager-niveau Node.js API) om vergelijkbare functionaliteit te bereiken. Hoewel cls-hooked nog steeds veel wordt gebruikt, heeft AsyncLocalStorage over het algemeen de voorkeur vanwege de ingebouwde aard en verbeterde prestaties.

Async Hooks (async_hooks)

Async Hooks bieden een lager-niveau API voor het volgen van de levenscyclus van asynchrone operaties. Hoewel AsyncLocalStorage bovenop Async Hooks is gebouwd, is het direct gebruiken van Async Hooks vaak complexer en minder performant. Async Hooks zijn geschikter voor zeer specifieke, geavanceerde use-cases waar fijnmazige controle over de asynchrone levenscyclus vereist is. Vermijd het direct gebruiken van Async Hooks tenzij het absoluut noodzakelijk is.

Waarom AsyncLocalStorage verkiezen boven cls-hooked?

• Ingebouwd: AsyncLocalStorage is onderdeel van de Node.js core, waardoor externe afhankelijkheden overbodig zijn.
• Prestaties: AsyncLocalStorage is over het algemeen performanter dan cls-hooked vanwege de geoptimaliseerde implementatie.
• Onderhoud: Als een ingebouwde module wordt AsyncLocalStorage actief onderhouden door het Node.js core team.

Overwegingen en Beperkingen

Hoewel AsyncLocalStorage een krachtig hulpmiddel is, is het belangrijk om op de hoogte te zijn van de beperkingen:

• Contextgrenzen: AsyncLocalStorage propageert context alleen binnen dezelfde executiecontext. Als u gegevens doorgeeft tussen verschillende processen of servers (bijv. via message queues of gRPC), moet u de contextgegevens nog steeds expliciet serialiseren en deserialiseren.
• Geheugenlekken: Onjuist gebruik van AsyncLocalStorage kan potentieel leiden tot geheugenlekken als de contextgegevens niet correct worden opgeruimd. Zorg ervoor dat u asyncLocalStorage.run() correct gebruikt en vermijd het opslaan van grote hoeveelheden gegevens in de AsyncLocalStorage.
• Complexiteit: Hoewel AsyncLocalStorage contextpropagatie vereenvoudigt, kan het ook complexiteit aan uw code toevoegen als het niet zorgvuldig wordt gebruikt. Zorg ervoor dat uw team begrijpt hoe het werkt en de best practices volgt.
• Geen vervanging voor globale variabelen: AsyncLocalStorage is *geen* vervanging voor globale variabelen. Het is specifiek ontworpen voor het propageren van context binnen een enkel verzoek of transactie. Overmatig gebruik kan leiden tot sterk gekoppelde code en het testen bemoeilijken.

Best Practices voor het Gebruik van AsyncLocalStorage

Om AsyncLocalStorage effectief te gebruiken, overweeg de volgende best practices:

• Gebruik Middleware: Gebruik middleware om de AsyncLocalStorage te initialiseren en contextgegevens aan het begin van elk verzoek op te slaan.
• Sla Minimale Gegevens op: Sla alleen essentiële contextgegevens op in de AsyncLocalStorage om de geheugenoverhead te minimaliseren. Vermijd het opslaan van grote objecten of gevoelige informatie.
• Vermijd Directe Toegang: Encapsuleer de toegang tot de AsyncLocalStorage achter goed gedefinieerde API's om sterke koppeling te vermijden en de onderhoudbaarheid van de code te verbeteren. Maak helper-functies of klassen om contextgegevens te beheren.
• Denk aan Foutafhandeling: Implementeer foutafhandeling om gevallen waarin de AsyncLocalStorage niet correct is geïnitialiseerd, netjes af te handelen.
• Test Grondig: Schrijf unit- en integratietests om te verzekeren dat de contextpropagatie werkt zoals verwacht.
• Documenteer het Gebruik: Documenteer duidelijk hoe AsyncLocalStorage in uw applicatie wordt gebruikt om andere ontwikkelaars te helpen het contextpropagatie-mechanisme te begrijpen.

Integratie met OpenTelemetry

OpenTelemetry is een open-source observeerbaarheidsframework dat API's, SDK's en tools biedt voor het verzamelen en exporteren van telemetriegegevens (bijv. traces, metrics, logs). AsyncLocalStorage kan naadloos worden geïntegreerd met OpenTelemetry om trace-context automatisch door te geven over asynchrone operaties.

OpenTelemetry is sterk afhankelijk van contextpropagatie om traces over verschillende services te correleren. Door AsyncLocalStorage te gebruiken, kunt u ervoor zorgen dat de trace-context correct wordt doorgegeven binnen uw Node.js-applicatie, waardoor u een uitgebreid gedistribueerd tracing-systeem kunt opbouwen.

Veel OpenTelemetry SDK's maken automatisch gebruik van AsyncLocalStorage (of cls-hooked als AsyncLocalStorage niet beschikbaar is) voor contextpropagatie. Raadpleeg de documentatie van uw gekozen OpenTelemetry SDK voor specifieke details.

Conclusie

AsyncLocalStorage is een waardevol hulpmiddel voor het beheren van asynchrone contextpropagatie in server-side JavaScript-applicaties. Door het te gebruiken voor request tracing, authenticatie, logging en andere use-cases, kunt u robuustere, observeerbare en beter onderhoudbare applicaties bouwen. Hoewel er alternatieven zoals cls-hooked en Async Hooks bestaan, is AsyncLocalStorage over het algemeen de voorkeurskeuze vanwege de ingebouwde aard, prestaties en gebruiksgemak. Vergeet niet de best practices te volgen en rekening te houden met de beperkingen om de mogelijkheden ervan effectief te benutten. De mogelijkheid om verzoeken te volgen en gebeurtenissen te correleren over asynchrone operaties is cruciaal voor het bouwen van schaalbare en betrouwbare systemen, vooral in microservices-architecturen en complexe gedistribueerde omgevingen. Het gebruik van AsyncLocalStorage helpt dit doel te bereiken, wat uiteindelijk leidt tot betere debugging, prestatiemonitoring en algehele applicatiegezondheid.